fix(agc): mirror only unimported tails of registered heaps - #8380

What

When a registered heap exceeds the host-import budget, import the fitting prefix and mirror only its unimported tail. Previously a budget refusal could mirror the whole registration, including bytes already represented by an import. Keep the original registration identity for lifetime tracking while keying and allocating each mirror by its selected physical range.

Rebased onto main ea695358ee1ccaf3d108b720d82c5d88413d43dc, dropping the merged #7292 prerequisite. This PR contains the standalone resource fix and a focused test follow-up. The partial mirror uses main's #7647 reservation and sparse-resident accounting: reserveHeapBytes, ResidentBuffer::Create, accounted, listed and unlistMirror, including reservation rollback and retirement. Removed the extra blank lines after importPieces.

Related work: #9514 changes budget-refusal eviction before the address-copy cap. Agreed merge order is #9514 first, then rebase this PR onto the resulting main. Its implementation is excluded from this branch. The local combined build needs one bookkeeping adaptation in #9514's added retry path: replace imported.push_back(range->address) with imported.emplace_back(range->address, range->address + range->bytes) to match this PR's imported-range tracking.

Tested

• Windows 11 Pro 10.0.26200; NVIDIA RTX 4070, driver 610.88; GCC 15.2, Release, SPIR-V Tools enabled. Rebuilt complete libs and recorded local library hashes. No game or shader patches included.
• Same 16 focused tests on clean main ea695358ee1ccaf3d108b720d82c5d88413d43dc and candidate 41d4affd6191d6b799f838a8e56b216335b563a2: 16/16 passed on each platform (Windows RTX 4070 and Ubuntu 26.04.1 under WSL2, lavapipe / llvmpipe LLVM 21.1.8, Mesa 26.0.8). Linux main was rerun during this follow-up; Windows main results are from the unchanged pinned base's prior matched run. Used ANYPS5_REQUIRE_VULKAN=1, ANYPS5_NO_SHADER_CACHE=1, VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation and verbose CTest with a 30-second individual timeout. Verified the layer actually loaded; all four logs have no missing-layer warnings, skipped tests or VUID- errors.
• Coverage: graphics/BDA device and span reads, real GPU resident heap mirrors, CPU device selection, draw-pipeline span reads, copied/sparse mirror unwatch with and without space caching, sparse budget, run unwatch, address-space teardown and specialized BDA shader ABI none/full.
• Prior head 57851797857808c16b0380ba08f8df118e02dc36, composed locally with fix(agc): an address-based build evicts idle imports instead of copying past the cap #9514 head f2e4290e9c75880fc964f56528414713d2e21e96 and the imported-range bookkeeping adaptation above: 18/18 passed, adding agc_address_copy_cap and agc_address_copy_cap_remembered. Actual validation layer loaded, no skipped tests, missing-layer warnings or VUID- errors. This composition predates the test-only follow-up and remains local.
• Reproduced the old CI failure locally on lavapipe: read heap 0x769c65ff0000 had no imported prefix; the lower-addressed write heap 0x769c657e0000 had the 131072-byte prefix. The test incorrectly assumed allocation order equaled registry address order. This was not a sparse-block granularity difference. The follow-up verifies the exact prefix on the selected heap and tests both allocation orders with resident and copied fallback mirrors.
• Negative control: the updated real GPU regression over main fails the first registered heap has no exact two-block imported prefix. The earlier Windows-only mocked cases also fail on main (a heap exceeding the import budget did not import its fitting prefix). No Vulkan validation errors in the negative controls.
• partialHeapImportBudgetTests covers a 384 KiB registration with a 256 KiB imported prefix and exact 128 KiB tail, mirror replacement, first/last bytes, CPU writes, GPU write-back, short final windows, neighbors and retirement. Added the simultaneous import-window and budget-limit case.
• Real GPU regression exercises sparse-backed and copied fallback mirrors for an 8 MiB registration with an asserted 128 KiB imported prefix. Its sparse tail accounts for 64 KiB when the selected heap is the read heap, or 128 KiB when it is the write heap (tail data plus the GPU-written block). Copied fallback accounts for the 8 MiB minus the verified prefix. GPU reads and subsequent CPU edits preserve exact values and neighboring bytes. These are mirror accounting results, not total physical VRAM, process RAM or FPS measurements; allocator slabs may remain allocated.
• Gameplay, cross-title and extended stability checks have not been rerun on this revision. No FPS or process-memory improvement is claimed.
• git diff --check and tools/check_conventions.py --base upstream/main pass. The required --base origin/main invocation reports inherited findings against the older fork main; those findings are outside this topic diff.

Checklist

• Based on current main; no other open PR implements the same functions — related fix(agc): an address-based build evicts idle imports instead of copying past the cap #9514 composition and merge order described above
• One topic per PR; follow-ups go in a new PR
• No comments in code except technical debt
• Unimplemented paths throw (NotImplemented_nid_no_patch); silent stubs are listed under Silent stubs in their library's technical debt file
• No notes, investigation .md files or images added to the repository (attach them to this PR)
• New third-party code is a submodule built from source
• Generic behaviour, not specific to one title
• Depends on: fix(agc): an address-based build evicts idle imports instead of copying past the cap #9514 for merge order; its code is not included
• Fixes: none
• Unblocks: none; no current gameplay claim
• GPUs tested: NVIDIA RTX 4070, driver 610.88, Windows 11 Pro 10.0.26200; lavapipe / llvmpipe LLVM 21.1.8, Mesa 26.0.8, Ubuntu 26.04.1 under WSL2
• AI-assisted: yes